Skip to main content

Arbitrary Message Bridge

The native Arbitrary Message Bridge (AMB) allows user to send arbitrary data between Gnosis Chain and Ethereum. This allows Gnosis contracts to send data and trigger contract functions on Ethereum and other chains, and vice versa.

The AMB is a key bridge primitive that is used inside higher-order bridges like the Omnibridge native token bridge, and is part of the Tokenbridge Architecture.

With Telepathy added as the 8th validator, AMB bridge is now more secure with trustless zero-knowledge light client technology. Due to the light client finality requirements (at least 23mins on Ethereum), the transactions will take approx. 30mins to be signed by the bridge. However, users can still use 3rd party bridges (Jumper.exchange, Connext, Hop) without any impact. For more details, check out how AMB & Omnibridge works with Telepathy validator.

Key Information​

Overview​

Detail
Frontend URLN/A
Trust Model4-of-8 Validator Multisig
Governance8-of-16 Multisig
Governance ParametersValidators
Bug Bountyup to $2m
Bug ReportingImmunefi

Key Contracts​

Ethereum​

ContractAddress
Omnibridge Multi-Token Mediator0x88ad09518695c6c3712AC10a214bE5109a655671
AMB (Foreign)0x4C36d2919e407f0Cc2Ee3c993ccF8ac26d9CE64e
AMB/OmniBridge wETH Router Helper0xa6439Ca0FCbA1d0F80df0bE6A17220feD9c9038a

Fees & Daily Limits​

As the Arbitrary Message Bridge is a message passing bridge, there are no fees or daily limits associated with it.

Bridge Validators​

Bridge Governance​

How it works​

Terminology​

  • Home (Native) Network: Of the two networks being bridged between, the home or native network is the one with fast and inexpensive operations. All bridge operations to collect validator confirmations are performed on this side of the bridge. It is the Gnosis Chain in this case.
  • Foreign Network: Can be any EVM chain, generally it refers to Ethereum.
  • Originating Contract: An arbitrary contract where the message originates, typically this is where the user interacts and requests for a function to be invoked on another network.

Call a cross-chain method via AMB:​

function requireToPassMessage (address _contract,
                                bytes _data,
                                uint256 _gas) external;
paramdetails
_contractaddress of contract on other network
_dataencoded bytes of the method selector and the params that will be called in the contract on the other side
_gasgas to be provided in execution of the method call on the other side

Foreign Network to Home Network​

  1. User calls foo() on the originating contract
  2. Originating contract calls requireToPassMessage() on Foreign Bridge contract, and encodes foo(), target address, and gas limit used on the other chain for executing a message.
  3. UserRequestForAffirmation event is emitted, and listening validators relay the message to the Home side where signatures are collected
  4. executeAffirmation() is called on the Home Bridge contract by a validator once enough signatures are collected.
  5. Home bridge contract decodes the message and calls foo() on the target contract.

Home Network to Foreign Network​

  1. User calls foo() on an originating contract
  2. Originating contract calls requireToPassMessage() on Home Bridge contract, and encodes foo(), target address, and gas limit used on the other chain for executing a message.
  3. Signatures are collected from validators by calling submitSignatures(), and once enough are collected CollectedSignatures() event is emitted.
  4. Message is relayed to the Foreign Bridge contract, and executeSignatures() is called
  5. Foreign bridge contract decodes the message and calls foo() on target contract

How it works with Telepathy validator​

AMB&Omnibridge with Telepathy Validator

** In the graph above, light green compoenents work as the same as Call a cross-chain method via AMB on the previous section.

There are 5 key components for Telepathy validator in AMB & Omnibridge:

Off chain

  1. Telepathy Relayer: Provide merkle proof for Telepathy PubSub, that the userRequestForAffirmation event was emitted on Ethereum.
  2. Telepathy Operator: For every ~12 mins (2 epoch in Ethereum), call Telepathy Light Client to update header.

On Gnosis Chain

  1. Telepathy PubSub: Verify the Merkle proof against the block header and publish the event.
  2. Telepathy Light Client: Generate a proof of consensus for block header and verify on-chain.
  3. Telepathy Validator: Subscribe to UserRequestForAffirmation event, and handle the published event by calling executeAffirmation() on AMB.

Once the user initiate cross-chain method via AMB on Ethereum, it will take ~12 mins for the transaction to get finalized in block and for Telepathy light client to obtain the block header information. Thus, user has to wait for approx. 30 mins for the message to get bridged to Gnosis Chain.

RoleAddress
Telepathy PubSub0x30Ec3049F571cf61099535bd73EcbC8968e6311a
Telepathy Validator0x456c255a8bc1f33778603a2a48eb6b0c69f4d48
Telepathy Light Client0x251cee0641afed44f625fafa1cd2b410f7868591

For more details, check out Telepathy Validator for Omnibridge and https://docs.telepathy.xyz/.

How to check if AMB is down (not relaying message)​

In certain circumstances, i.e. hardfork, AMB will be planned for downtime (not relaying message) to ensure security of the bridge. Planned downtime will be announced in public channel like Discord and Twitter, prior to the event.
There is also another way to check whether the AMB is down or not by reading maxGasPerTx value on AMB contract.

In the current configuration, maxGasPerTx is set to 4000000 on Ethereum and 2000000 on Gnosis Chain.

The AMB is down when maxGasPerTx is set to 0, only by owner of the contract.

By setting maxGasPerTx to 0, the condition in _sendMessage() will not pass, meaning, the bridge is down/stopped.

Security Considerations for Receiving a Call​

ConcernRemediation
AuthorizationCheck the address of invoking contract using messageSender()
AuthorizationCheck that msg.sender is the address of the bridge contract
Replay AttacktransactionHash() allows for checking of a hash of the transaction that invoked the requireToPassMessage() call. The invoking contract (in some cases, the mediator contract) is responsible for providing a unique sequence (can be a nonce) as part of the _data param in the requireToPassMessage() function call

Mediator Contracts​

A mediator contract is needed if there is an approval flow, such as when transferring an NFT or ERC-20 token. For a more in-depth explanation, see the Omnibridge page.

AMB Components​

ComponentDescription
System ContractsAMB Implementation Contracts (Home Bridge and Foreign Bridge), Governance Multisigs, gas limit helpers, failed call management helpers (for when gas estimate was insufficient), and fee management helpers to collect fees
OraclesContainerized microservices that listen for on-chain events and send confirmations to relay messages. More on them here.
DevOpsBridge monitoring, ALM, docker compose, ansible playbooks
dApp Contractsextensions (pair mediator contracts on both sides of the AMB), such as the Omnibridge

Use Cases of AMB​

  • ERC-to-ERC Bridges: AMB-ERC-TO-ERC mode enables the transfer of ERC tokens to the Foreign Mediator, which will interact with Foreign AMB Bridge to mint wrapped ERC-667 tokens on the Home Network. Complimentarily, the mode enables the transfer ERC20 or ERC-667 tokens to the Home Mediator, which will interact with Home AMB Bridge to unlock ERC20 tokens on the Foreign network. This is used by the Omnibridge.
  • ERC-to-Native Bridges: ERC-TO-NATIVE mode enables the user to send ERC20 tokens to the Foreign Bridge and receive native coins from the Home Bridge Complimentarily, then can send native coins to the Home Bridge to unlock ERC20 tokens from the Foreign Bridge. The home network nodes must support a consensus engine that allows using a smart contract for block reward calculation. This mode is used by the xDai Bridge
  • Message Passing: ARBITRARY-MESSAGE mode enables the capability to invoke a Home/Foreign Bridge contract to send a message that will be executed on the other Network. This can be an arbitrary contract method invocation.

Resources​